Using Git and GitHub in the Scottish Government
 

Alice Byers, Data Innovation Team

Scottish Government

Aims

  • These slides aim to demonstrate the use of Git and GitHub in the Scottish Government, with consideration to limitations of the SCOTS network.

  • An understanding of the concept of version control, Git and GitHub is assumed. More information can be found in these introduction to version control slides.

  • Further guidance and resources for using version control on SCOTS are available on the Statistics Group sharepoint site.

Contents

Git setup

Install Git

  • Make an iFix request for “Git version 2.21.0.windows.1”

  • Git is a free and open-source software and therefore does not incur a cost to install

Git Bash

  • Git Bash is a command line interface for using Git

  • It is installed with Git

Git Bash

  • Some basic commands include:

    • pwd; prints present working directory

    • ls; lists files contained in working directory

    • cd <filepath>; changes working directory

  • ONS Learning Hub has further training on Command Line Basics

Set name and email

  • Your name and email is linked to every commit you make using Git and cannot be changed retrospectively, therefore it is important to do this.

  • If you plan to use GitHub, make sure your user name and email address match those associated with your GitHub account.

To do this in Git Bash, run:

git config --global user.name alicebyers5
git config --global user.email alice.byers@gov.scot

To check this has worked:

git config --global user.name
alicebyers5

git config --global user.email
alice.byers@gov.scot

Git workflow

Example project folder


Open Git Bash in working directory

  • Right click in working folder and select ‘Git Bash here’

  • Open Git Bash from Windows start menu

  • Use cd command to change directory to your working folder

Initiate Git respository

  • Run git init to initiate Git. This will create a .git folder within your project. (Note: you only need to do this once per project.)

Create a gitignore file

  • A gitignore file defines what files should not be tracked by Git. This is especially important if you plan on using GitHub as sensitive information should not be made available there.

  • Generally, the following should be ignored:

    • Data files

    • Passwords or credentials

    • Code that contains sensitive information

    • Configuration files

Create a gitignore file

To tell Git to ignore these files:

  • Create a new file in your directory called .gitignore. This can be done in the usual way in File Explorer, or by using the touch command in Git Bash.

  • Open the .gitignore file in a text editor (or R) and add names of folders and files to be ignored.

    • This is a good example gitignore that contains many common data and R files. Copy the contents to the file you’ve just created.

git status

  • Use git status to show a summary of your Git repository - run this often to check that your other git commands have done what you expect them to do

  • Notice that data.csv is not listed here. This is because we have told Git to ignore csv files in the gitignore.

git add

  • Use git add to ‘stage’ files for the next commit

    • Either list the files you’d like to stage; e.g. git add code.R, or

    • To stage all tracked files, use a full stop; e.g. git add .

git add

  • Use git status to check that the correct files have been staged

  • Files names are now coloured green and listed under ‘changed to be committed’

git commit

  • Use git commit to add the files to the Git history.

    • Accompany the commit with a message to give a short and informative description of the changes.

Your first commit

  • Running git status again shows that there are no further changes to commit

Your first commit

  • Running git log --oneline will give a short summary of the commit history

Make a change

  • Now, let’s make a change to code.R. Define a new variable called y.

Make a change

  • Run git status to check that Git has recognised the change

git diff

  • Run git diff to inspect what changes have been made to code.R. Green text highlights additions and red text highlights deletions.

Stage and commit the change

  • Use git add and git commit to stage and commit the change to code.R.

Stage and commit the change

  • Use git log to view the Git history - there are now two commits

Using Git with RStudio Integration

RStudio

  • Not all Git functionality is available from RStudio, but it can be more user-friendly and convenient if you’re working with R

  • Changes are listed in the Git pane (usually in the top right window)

Open the commit window

  • Click the ‘Commit’ button to open up the commit window

Commiting a change from RStudio

  • Like Git Bash, you need to both stage and commit the change

  • To stage, tick the box next to each file you’d like to add (top-left pane)

  • To commit, enter a message and click ‘Commit’ (top-right pane)

GitHub and
Data Science Scotland

Create GitHub account

  • Use your work email address

    • Note that you can associate multiple email addresses with your account. Just made sure you author commits for work projects with your gov.scot address.
  • Enable two-factor authentication

  • Add a (work appropriate) photo and username

  • Add your contact details and employer

  • Make your gov.scot email address public on your profile

Join Data Science Scotland organisation

  • Work projects should all be hosted from the Data Science Scotland organisation

  • Request to join the organisation

  • Once your request has been accepted, you will be free to create Git repositories in Data Science Scotland

Create a repository

Using Git with GitHub

One time setup - create SSH key

  • Generate an SSH key in Git Bash

    ssh-keygen -t ed25519 -C "your_email@example.com"

    (this should be the email registered with your Github account)

  • Git Bash will ask where you want to create the key. The default location is recommended. (You can find your SSH home in Git Bash by running: echo ~/.ssh.)

  • Git Bash will ask if you want to set a passphrase. This is a local password that will be requested each time you use the key. It is OK not to set a passphrase here by just pressing enter twice.

One time setup - add SSH key to GitHub account

  • Copy the SSH key:

    # Navigate to the directory where you've saved your SSH key
    cd ~/.ssh
    
    # Print the contents of the public SSH key file
    cat id_ed25519.pub

    Copy the returned value from Git Bash.

  • Add the copied SSH key to your GitHub account:

Clone repository from GitHub

  • Now you have an SSH key setup, you should use the SSH URL to clone repositories from GitHub.

  • Click the green ‘Code’ button and under ‘Clone’, select ‘SSH’, and copy the address.

Clone repository from GitHub

  • Open Git Bash and navigate to the directory you’d like to clone the repository to

  • Use git clone to clone the repository

screenshot

Clone repository from GitHub

  • Git Bash is still running from the parent directory. To move to the cloned repository, use cd

screenshot

Push to GitHub

Pull from GitHub

There’s still more!

Other concepts

  • Branches

  • Pull requests and code review

  • Issues

  • Project management

Resources

Contact me

Alice Byers, Data Innovation Team

Scottish Government